/**
 * \addtogroup R2VS R2VS API
 * @{
 *  This file specifies the Samsung R2VS API for Windows Mobile Devices.
 *
 * R2VS is an audio processing system that enhances a phone's audio output by augmenting 
 * the sound reproduction quality of an audio source to enrich a user's audio experience.  
 * One example of such a system is to simulate the true (physical) surround sound experience 
 * while using headphones. 
 *
 * Copyright &copy; 2009 Samsung Electronics
 *   
 * File: smiR2VS.h
 */

#ifndef _SMI_R2VS_H_
#define _SMI_R2VS_H_


#include "smiSDK.h"


/**
*  Specifies error codes specific to the R2VS API.
*/
typedef enum 
{
    SMI_R2VS_RESULT_HEADSET_NOT_PRESENT   =  SMI_R2VS_RESULT_BASE
} SmiR2VSResultCode;

/**
 *  R2VS operating modes.
 *
 */
typedef enum
{
	SMI_R2VS_MODE_NONE,
	SMI_R2VS_MODE_3D_SOUND,
	SMI_R2VS_MODE_MTHEATER
} SmiR2VSMode;

/**
 *  Sets the R2VS operating mode.
 * 
 *  @param mode [in]			R2VS mode.
 *
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiR2VSSetMode (SmiR2VSMode mode);

/**
 *  Gets the current R2VS operating mode.
 * 
 *  @param mode [out]			Current R2VS mode.
 *
 *  @return 
 * 								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiR2VSGetMode (SmiR2VSMode *mode);

/**
 *  R2VS 3D Sound modes.
 *
 */
typedef enum
{
	SMI_R2VS_3D_SOUND_MODE_WIDE,
	SMI_R2VS_3D_SOUND_MODE_DYNAMIC,
	SMI_R2VS_3D_SOUND_MODE_SURROUND
} SmiR2VS3DSoundMode;

/**
 *  R2VS 3D Sound Equalizer presets.
 *
 */
typedef enum
{
	SMI_R2VS_3D_SOUND_EQU_DEFAULT,
	SMI_R2VS_3D_SOUND_EQU_ROCK,
	SMI_R2VS_3D_SOUND_EQU_FULL_BASS,
	SMI_R2VS_3D_SOUND_EQU_FULL_BASS_AND_TREBLE,
	SMI_R2VS_3D_SOUND_EQU_LIVE,
	SMI_R2VS_3D_SOUND_EQU_DANCE,
	SMI_R2VS_3D_SOUND_EQU_POP,
	SMI_R2VS_3D_SOUND_EQU_FULL_TREBLE,
	SMI_R2VS_3D_SOUND_EQU_CLUB,
	SMI_R2VS_3D_SOUND_EQU_PARTY,
	SMI_R2VS_3D_SOUND_EQU_LARGE_HALL,
	SMI_R2VS_3D_SOUND_EQU_SOFT,
	SMI_R2VS_3D_SOUND_EQU_SOFT_ROCK
} SmiR2VS3DSoundEqualizerPreset;

/**
 *  Specifies settings for the R2VS 3D Sound mode. 
 *
 */
typedef struct
{
	/**
	 * The 3D Sound processing mode. 
	 */
	SmiR2VS3DSoundMode mode ;

	/**
	 * The degree to which audio is processed, in percent (1-100), with higher numbers signifying a larger amount of 3D effect.
	 */
	UINT gainLevel ;

	/**
	 * The 3D Sound mode's equalizer preset setting.
	 */
	SmiR2VS3DSoundEqualizerPreset equalizer ;
} SmiR2VS3DSoundSettings;

/**
 *  Sets the R2VS 3D Sound settings.
 * 
 *  @param settings [in]		R2VS 3D Sound settings.
 *
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiR2VSSet3DSoundSettings (SmiR2VS3DSoundSettings settings);

/**
 *  Gets the current R2VS 3D Sound settings.
 * 
 *  @param settings [out]		Pointer to the current R2VS 3D Sound Settings.
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiR2VSGet3DSoundSettings(SmiR2VS3DSoundSettings *settings);

/**
 *  R2VS M-Theater processing modes.
 *
 */
typedef enum
{
	SMI_R2VS_MTHEATER_MODE_CLOCKWISE=1,
	SMI_R2VS_MTHEATER_MODE_COUNTER_CLOCKWISE,
	SMI_R2VS_MTHEATER_MODE_FRONT_PANNING,
	SMI_R2VS_MTHEATER_MODE_RANDOM,
	SMI_R2VS_MTHEATER_MODE_NORMAL,
	SMI_R2VS_MTHEATER_MODE_FRONT,
	SMI_R2VS_MTHEATER_MODE_BACK,
	SMI_R2VS_MTHEATER_MODE_MONO,
	SMI_R2VS_MTHEATER_MODE_STEREO
} SmiR2VSMTheaterMode;

/**
 *  Specifies settings for the R2VS M-Theater processing mode.
 *
 */
typedef struct
{
	/**
	 * The M-Theater processing mode. 
	 */
	SmiR2VSMTheaterMode mode ;

	/**
	 * The degree to which audio is processed, in percent (1-100), with higher numbers signifying a larger amount of M-Theater effect.
	 */
	UINT gainLevel ;
} SmiR2VSMTheaterSettings;

/**
 *  Sets the R2VS M-Theater settings.
 * 
 *  @param settings [in]		R2VS MTheater Settings.
 *
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is invalid
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiR2VSSetMTheaterSettings (SmiR2VSMTheaterSettings settings);

/**
 *  Gets the R2VS current M-Theater settings.
 * 
 *  @param settings [out]		Current R2VS M-Theater Settings.
 *  @return 
 *								SMI_SUCCESS on success
 * \n							SMI_ERROR_INVALID_PARAMETER if the input parameter is NULL
 * \n							SMI_ERROR_DEVICE_NOT_FOUND if the device is not present or supported
 * \n							SMI_ERROR_UNKNOWN for all other failures
 */ 
SMI_API SMI_RESULT SmiR2VSGetMTheaterSettings (SmiR2VSMTheaterSettings *settings);

#endif /* _SMI_R2VS_H_ */
/* @} */


